<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
<html>
<head>
  <meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
  <link rel="stylesheet" href="docgen-resources/docgen.css" type="text/css">
  <meta name="generator" content="FreeMarker Docgen (DocBook 5)">
  <title>
    FreeMarker Manual - attempt, recover
  </title>
    <script type="text/javascript" src="docgen-resources/jquery.js"></script>
    <script type="text/javascript" src="docgen-resources/linktargetmarker.js"></script>
</head>
<body>

    <div class="navigation">
    <div class="breadcrumb">
<span class="breadcrumb">        You are here:
          <a href="index.html">Book</a>
            <b>></b>
          <a href="ref.html">Reference</a>
            <b>></b>
          <a href="ref_directives.html">Directive Reference</a>
            <b>></b>
          attempt, recover
</span>    </div>
    <div class="bookmarks">
<span class="bookmarks">Bookmarks:
<a href="alphaidx.html">Alphabetical Index</a>, <a href="gloss.html">Glossary</a>, <a href="ref.html">Reference</a>, <a href="app_faq.html">FAQ</a>, <a href="api/index.html">Java API</a>, <a href="../index.html">FreeMarker Home</a></span>    </div>
    <div class="pagers">
      <div class="pagersVerticalSpacer"><img src="docgen-resources/img/none.gif" width="1" height="1" alt="" hspace="0" vspace="0" border="0"/></div>
<div class="pagerButton"><a href="ref_directive_visit.html"><span class="hideA">Next page: </span>visit, recurse, fallback</a></div><div class="pagerButton"><a href="ref_directive_nt.html">Previous page</a></div><div class="pagerButton"><a href="ref_directives.html">Parent page</a></div><div class="pagerButton"><a href="index.html">Contents</a></div>      <div class="pagersVerticalSpacer"><img src="docgen-resources/img/none.gif" width="1" height="1" alt="" hspace="0" vspace="0" border="0"/></div>
    </div>
    </div>

<div id="mainContent">

  
  
  
  
  <h1 class="rank_section1"
        id="pageTopTitle">
<a name="ref_directive_attempt"></a>attempt, recover  </h1>
    
    <div class="toc">
      <p>
        <b>
            Page Contents
        </b>
      </p>
      
  <ul class="noMargin">
      <li style="padding-bottom: 0.5em"><i><a href="#docgen_afterTheTOC">Intro.</a></i></li>
      <li>
        <a href="#autoid_120">Synopsis</a>
      </li>
      <li>
        <a href="#autoid_121">Description</a>
      </li>
  </ul>
    </div>
    <a name="docgen_afterTheTOC"></a>
    
<a name="ref.directive.attempt"></a><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;">
   <p class="rank_note">Note</p>

          <p>The above format is supported starting from 2.3.3, earlier it
          was
          <tt style="color: #A03D10">&lt;#attempt&gt;<i style="color: #DD4400">...</i>&lt;#recover&gt;<i style="color: #DD4400">...</i>&lt;/#recover&gt;</tt>,
          which is still supported for backward compatibility. Furthermore,
          these directives were introduced with FreeMarker 2.3.1, so they
          aren't exist in 2.3.</p>
        </div>

            
  
  
  
  <h2 class="rank_section2"
        >
<a name="autoid_120"></a>Synopsis  </h2>


          <pre class="metaTemplate">
<tt style="color: #A03D10">&lt;#attempt&gt;
  <i style="color: #DD4400">attempt block</i>
&lt;#recover&gt;
  <i style="color: #DD4400">recover block</i>
&lt;/#attempt&gt;
</tt>
</pre>


          <p>Where:</p>

              <div class="itemizedlist">
<ul>
            <li>
              <tt style="color: #A03D10"><i style="color: #DD4400">attempt
              block</i></tt>: Template block with any content.
              This will be always executed, but if an error occurs during
              that, all output from this block is rolled back, and the
              <tt style="color: #A03D10"><i style="color: #DD4400">recover block</i></tt> will
              be executed.
            </li>

            <li>
              <tt style="color: #A03D10"><i style="color: #DD4400">recover
              block</i></tt>: Template block with any content.
              This will be executed only if there was an error during the
              execution of the <tt style="color: #A03D10"><i style="color: #DD4400">attempt
              block</i></tt>. You may print an error messages
              here and such.
            </li>
          </ul>    </div>


          <p>The <tt style="color: #A03D10"><i style="color: #DD4400">recover</i></tt> is
          mandatory. <tt style="color: #A03D10">attempt</tt>/<tt style="color: #A03D10">recover</tt> can
          be nested freely into other <tt style="color: #A03D10"><i style="color: #DD4400">attempt
          block</i></tt>s or <tt style="color: #A03D10"><i style="color: #DD4400">recover
          block</i></tt>s.</p>
        
            
  
  
  
  <h2 class="rank_section2"
        >
<a name="autoid_121"></a>Description  </h2>


          <p>These directives are used if you want the page successfully
          outputted even if the outputting of a certain part of the page
          fails. If an error occurs during the execution of the
          <tt style="color: #A03D10"><i style="color: #DD4400">attempt block</i></tt>, then
          the template execution is not aborted, but the
          <tt style="color: #A03D10"><i style="color: #DD4400">recover block</i></tt> is
          executed instead of the <tt style="color: #A03D10"><i style="color: #DD4400">attempt
          block</i></tt>. If no error occurs during the
          execution of the <tt style="color: #A03D10"><i style="color: #DD4400">attempt
          block</i></tt>, then the
          <tt style="color: #A03D10"><i style="color: #DD4400">recover block</i></tt> is
          ignored. A simple example:</p>

          <div align="left" class="programlisting"><table bgcolor="#D8D8D8" cellspacing="0" cellpadding="0" border="0"><tr valign="top"><td height="1" width="1" bgcolor="black"><img src="docgen-resources/img/none.gif" width="1" height="1" alt="" hspace="0" vspace="0" border="0"/></td><td height="1" bgcolor="black"><img src="docgen-resources/img/none.gif" width="1" height="1" alt="" hspace="0" vspace="0" border="0"/></td><td height="1" width="1" bgcolor="black"><img src="docgen-resources/img/none.gif" width="1" height="1" alt="" hspace="0" vspace="0" border="0"/></td></tr><tr><td width="1" bgcolor="black"><img src="docgen-resources/img/none.gif" width="1" height="1" alt="" hspace="0" vspace="0" border="0"/></td><td><table bgcolor="#D8D8D8" cellspacing="0" cellpadding="4" border="0" width="100%" style="margin: 0px"><tr><td><pre style="margin: 0px">
Primary content
&lt;#attempt&gt;
  Optional content: ${thisMayFails}
&lt;#recover&gt;
  Ops! The optional content is not available.
&lt;/#attempt&gt;
Primary content continued&nbsp;<span style="font-size: 1pt"> </span></pre></td></tr></table></td><td width="1" bgcolor="black"><img src="docgen-resources/img/none.gif" width="1" height="1" alt="" hspace="0" vspace="0" border="0"/></td></tr><tr valign="top"><td height="1" width="1" bgcolor="black"><img src="docgen-resources/img/none.gif" width="1" height="1" alt="" hspace="0" vspace="0" border="0"/></td><td height="1" bgcolor="black"><img src="docgen-resources/img/none.gif" width="1" height="1" alt="" hspace="0" vspace="0" border="0"/></td><td height="1" width="1" bgcolor="black"><img src="docgen-resources/img/none.gif" width="1" height="1" alt="" hspace="0" vspace="0" border="0"/></td>      </tr>
</table>  </div>


          <p>If the <tt style="color: #A03D10">thisMayFails</tt> variable doesn't exist,
          then the output is:</p>

          <div align="left" class="programlisting"><table bgcolor="#CCFFCC" cellspacing="0" cellpadding="0" border="0"><tr valign="top"><td height="1" width="1" bgcolor="black"><img src="docgen-resources/img/none.gif" width="1" height="1" alt="" hspace="0" vspace="0" border="0"/></td><td height="1" bgcolor="black"><img src="docgen-resources/img/none.gif" width="1" height="1" alt="" hspace="0" vspace="0" border="0"/></td><td height="1" width="1" bgcolor="black"><img src="docgen-resources/img/none.gif" width="1" height="1" alt="" hspace="0" vspace="0" border="0"/></td></tr><tr><td width="1" bgcolor="black"><img src="docgen-resources/img/none.gif" width="1" height="1" alt="" hspace="0" vspace="0" border="0"/></td><td><table bgcolor="#CCFFCC" cellspacing="0" cellpadding="4" border="0" width="100%" style="margin: 0px"><tr><td><pre style="margin: 0px">
Primary content
  Ops! The optional content is not available.
Primary content continued&nbsp;<span style="font-size: 1pt"> </span></pre></td></tr></table></td><td width="1" bgcolor="black"><img src="docgen-resources/img/none.gif" width="1" height="1" alt="" hspace="0" vspace="0" border="0"/></td></tr><tr valign="top"><td height="1" width="1" bgcolor="black"><img src="docgen-resources/img/none.gif" width="1" height="1" alt="" hspace="0" vspace="0" border="0"/></td><td height="1" bgcolor="black"><img src="docgen-resources/img/none.gif" width="1" height="1" alt="" hspace="0" vspace="0" border="0"/></td><td height="1" width="1" bgcolor="black"><img src="docgen-resources/img/none.gif" width="1" height="1" alt="" hspace="0" vspace="0" border="0"/></td>      </tr>
</table>  </div>


          <p>If the <tt style="color: #A03D10">thisMayFails</tt> variable exists and
          it's value is <tt style="color: #A03D10">123</tt>, then the output is:</p>

          <div align="left" class="programlisting"><table bgcolor="#CCFFCC" cellspacing="0" cellpadding="0" border="0"><tr valign="top"><td height="1" width="1" bgcolor="black"><img src="docgen-resources/img/none.gif" width="1" height="1" alt="" hspace="0" vspace="0" border="0"/></td><td height="1" bgcolor="black"><img src="docgen-resources/img/none.gif" width="1" height="1" alt="" hspace="0" vspace="0" border="0"/></td><td height="1" width="1" bgcolor="black"><img src="docgen-resources/img/none.gif" width="1" height="1" alt="" hspace="0" vspace="0" border="0"/></td></tr><tr><td width="1" bgcolor="black"><img src="docgen-resources/img/none.gif" width="1" height="1" alt="" hspace="0" vspace="0" border="0"/></td><td><table bgcolor="#CCFFCC" cellspacing="0" cellpadding="4" border="0" width="100%" style="margin: 0px"><tr><td><pre style="margin: 0px">
Primary content
  Optional content: 123
Primary content continued&nbsp;<span style="font-size: 1pt"> </span></pre></td></tr></table></td><td width="1" bgcolor="black"><img src="docgen-resources/img/none.gif" width="1" height="1" alt="" hspace="0" vspace="0" border="0"/></td></tr><tr valign="top"><td height="1" width="1" bgcolor="black"><img src="docgen-resources/img/none.gif" width="1" height="1" alt="" hspace="0" vspace="0" border="0"/></td><td height="1" bgcolor="black"><img src="docgen-resources/img/none.gif" width="1" height="1" alt="" hspace="0" vspace="0" border="0"/></td><td height="1" width="1" bgcolor="black"><img src="docgen-resources/img/none.gif" width="1" height="1" alt="" hspace="0" vspace="0" border="0"/></td>      </tr>
</table>  </div>


          <p>The <tt style="color: #A03D10"><i style="color: #DD4400">attempt
          block</i></tt> has an all-or-none semantic: either
          the entire content of the <tt style="color: #A03D10"><i style="color: #DD4400">attempt
          block</i></tt> is output (when there was no error),
          or no output at all results from the execution of the
          <tt style="color: #A03D10"><i style="color: #DD4400">attempt block</i></tt> (when
          there was an error). For example, above, the failure happens after
          ``Optional content: '' was printed, still it is not there in the
          output before the ``Ops!''. (<span style="color:#333399; font-style:italic">This is
          implemented with the aggressive buffering of the output inside the
          <tt style="color: #A03D10"><i style="color: #DD4400">attempt block</i></tt>. Not
          even the <tt style="color: #A03D10">flush</tt> directive will send the output to
          the client.</span>)</p>

          <p>To prevent misunderstandings coming from the above example:
          <tt style="color: #A03D10">attempt</tt>/<tt style="color: #A03D10">recover</tt> is not (only)
          for handling undefined variables (for that use <a href="dgui_template_exp.html#dgui_template_exp_missing">missing value handler
          operators</a>). It can handle all kind of errors that occurs when
          the block is executed (i.e. not syntactical errors, which are
          detected earlier). And it's meant to enclose bigger template
          fragments, where error can occur at various points. For example, you
          have a part in your template that deals with printing
          advertisements, but that's not the primary content of the page, so
          you don't want your whole page be down just because some error
          occurs with the printing of the advertisements (say, because of a
          temporal database server faliure). So you put the whole
          advertisement printing into an <tt style="color: #A03D10"><i style="color: #DD4400">attempt
          block</i></tt>.</p>

          <p>In some environments programmers configure FreeMarker so that
          it doesn't abort template execution for certain errors, but
          continues execution, possibly after printing some error indicator to
          the output (<span style="color:#333399; font-style:italic">see more <a href="pgui_config_errorhandling.html">here...</a></span>). The
          <tt style="color: #A03D10">attempt</tt> directive doesn't consider such
          suppressed errors as errors.</p>

          <p>Inside a <tt style="color: #A03D10"><i style="color: #DD4400">recover
          block</i></tt> the error message of the error is
          available with the <tt style="color: #A03D10">error</tt> <a href="ref_specvar.html">special variable</a>. Don't forget that
          references to special variable are started with dot (for example:
          <tt style="color: #A03D10">${.error}</tt>).</p>

          <p><span style="color:#333399; font-style:italic">Errors occurring during template
          execution are always <a href="pgui_misc_logging.html">logged</a>, even if they occur inside
          an <tt style="color: #A03D10"><i style="color: #DD4400">attempt
          block</i></tt>.</span></p>
          
</div>

    <div class="navigation">
    <div class="pagers">
      <div class="pagersVerticalSpacer"><img src="docgen-resources/img/none.gif" width="1" height="1" alt="" hspace="0" vspace="0" border="0"/></div>
<div class="pagerButton"><a href="ref_directive_visit.html"><span class="hideA">Next page: </span>visit, recurse, fallback</a></div><div class="pagerButton"><a href="ref_directive_nt.html">Previous page</a></div><div class="pagerButton"><a href="ref_directives.html">Parent page</a></div><div class="pagerButton"><a href="index.html">Contents</a></div>      <div class="pagersVerticalSpacer"><img src="docgen-resources/img/none.gif" width="1" height="1" alt="" hspace="0" vspace="0" border="0"/></div>
    </div>
    <div class="breadcrumb">
<span class="breadcrumb">        You are here:
          <a href="index.html">Book</a>
            <b>></b>
          <a href="ref.html">Reference</a>
            <b>></b>
          <a href="ref_directives.html">Directive Reference</a>
            <b>></b>
          attempt, recover
</span>    </div>
    </div>

<table border=0 cellspacing=0 cellpadding=0 width="100%">
    <tr>
      <td colspan=2><img src="docgen-resources/img/none.gif" width=1 height=8 alt=""></td>
    <tr>
      <td align="left" valign="top"><span class="smallFooter">
            FreeMarker Manual -- For FreeMarker 2.3.16
            <br>
          HTML generated: 2009-12-08 08:38:54 GMT
      </span></td>
      <td align="right" valign="top"><span class="smallFooter">
          <a href="http://www.xmlmind.com/xmleditor/">
            <img src="docgen-resources/img/xxe.gif" alt="Edited with XMLMind XML Editor">
          </a>
      </span></td>
    </tr>
</table>
  <!-- Put pre-loaded images here: -->
  <div style="display: none">
    <img src="docgen-resources/img/linktargetmarker.gif" alt="Here!" />
  </div>
</body>
</html>

